package com.mapforge.map;

import com.mapforge.selection.Selection;
import com.mapforge.selection.SetOperationType;

/**
 * The {@link Mask} interface exists to relate classes which determine whether a
 * cell in a 2D matrix is valid for some sort of operation.
 * 
 * @author Will Morrison
 */
public interface Mask {

	/**
	 * Clears this {@link Mask} clean. Afterwards all cells are considered valid
	 * for operations, and this {@link Mask} will return true for all valid
	 * coordinate locations.
	 * 
	 * @see #checkMask(int, int)
	 */
	public void clearMask();

	/**
	 * Returns the width of this {@link Mask}
	 * 
	 * @return width of this mask
	 */
	public int getWidth();

	/**
	 * Returns the height of this {@link Mask}
	 * 
	 * @return height of this mask
	 */
	public int getHeight();

	/**
	 * Performs the specified set operation on all cells selected by the
	 * specified {@link Selection} using the specified value.
	 * 
	 * @see #checkMask(int, int, long)
	 * @see #clearMask()
	 * @see SetOperationType
	 * @param type
	 *            set operation type to perform using cells this mask considers
	 *            selected and points within the specified selection
	 * @param selection
	 *            specified selection
	 * @param value
	 *            value written in all cells
	 */
	public void setValues(SetOperationType type, Selection selection, long value);

	/**
	 * Returns whether the specified value passes a mask check against the value
	 * contained in the cell at the specified <code>(x, y)</code> coordinate. If
	 * so the cell at the <code>(x, y)</code> coordinate is valid for
	 * operations.
	 * 
	 * @param x
	 *            specified x location
	 * @param y
	 *            specified y location
	 * @param value
	 *            value to compare against mask value at specified
	 *            <code>(x, y)</code> location
	 * @return whether the passed value passes a mask check with value at
	 *         <code>(x, y)</code>
	 */
	public boolean checkMask(int x, int y, long value);
}
